From 582f46c5c3bfb4d8b156843c1212d1cd396aa2a3 Mon Sep 17 00:00:00 2001 From: Behnam Esfahbod Date: Wed, 30 Aug 2017 17:38:47 -0700 Subject: [PATCH] [src/doc/book] Update guide.md and 02-*.md from guide.md --- src/doc/MIGRATION_MAP | 2 +- src/doc/book/src/02-01-why-cargo-exists.md | 3 +- .../book/src/02-02-creating-a-new-project.md | 38 ++----- src/doc/book/src/02-05-project-layout.md | 12 +- .../src/02-06-cargo-toml-vs-cargo-lock.md | 104 ++++++++++++++++++ .../src/{02-06-tests.md => 02-07-tests.md} | 2 +- ...ion.md => 02-08-continuous-integration.md} | 2 +- src/doc/book/src/guide.md | 9 +- src/doc/guide.md | 102 +++++++++-------- 9 files changed, 184 insertions(+), 90 deletions(-) create mode 100644 src/doc/book/src/02-06-cargo-toml-vs-cargo-lock.md rename src/doc/book/src/{02-06-tests.md => 02-07-tests.md} (94%) rename src/doc/book/src/{02-07-continuous-integration.md => 02-08-continuous-integration.md} (98%) diff --git a/src/doc/MIGRATION_MAP b/src/doc/MIGRATION_MAP index b2dabd677..0cbfa3b3b 100644 --- a/src/doc/MIGRATION_MAP +++ b/src/doc/MIGRATION_MAP @@ -4,7 +4,7 @@ crates-io.md book/src/03-06-crates-io.md environment-variables.md book/src/03-04-environment-variables.md external-tools.md book/src/03-09-external-tools.md faq.md book/src/faq.md -guide.md +guide.md book/src/guide.md index.md manifest.md pkgid-spec.md diff --git a/src/doc/book/src/02-01-why-cargo-exists.md b/src/doc/book/src/02-01-why-cargo-exists.md index 6f08a2f4e..bdbfa9cec 100644 --- a/src/doc/book/src/02-01-why-cargo-exists.md +++ b/src/doc/book/src/02-01-why-cargo-exists.md @@ -7,5 +7,6 @@ To accomplish this goal, Cargo does four things: * Introduces two metadata files with various bits of project information. * Fetches and builds your project’s dependencies. -* Invokes `rustc` or another build tool with the correct parameters to build your project. +* Invokes `rustc` or another build tool with the correct parameters to build + your project. * Introduces conventions to make working with Rust projects easier. diff --git a/src/doc/book/src/02-02-creating-a-new-project.md b/src/doc/book/src/02-02-creating-a-new-project.md index f457f609e..678820f9e 100644 --- a/src/doc/book/src/02-02-creating-a-new-project.md +++ b/src/doc/book/src/02-02-creating-a-new-project.md @@ -59,7 +59,7 @@ $ ./target/debug/hello_world Hello, world! ``` -We can also use `cargo run` to compile and then run it, all in one step (you +We can also use `cargo run` to compile and then run it, all in one step (You won't see the `Compiling` line if you have not made any changes since you last compiled): @@ -70,42 +70,20 @@ $ cargo run Hello, world! ``` -You'll notice several new files and directories have been created: -```shell -$ tree . -. -├── Cargo.lock -├── Cargo.toml -├── src -│   └── main.rs -└── target - └── debug - ├── build - ├── deps - │   └── hello_world-2386c2fd0156916f - ├── examples - ├── hello_world - ├── hello_world.d - ├── incremental - └── native - -8 directories, 6 files -``` +You’ll now notice a new file, `Cargo.lock`. It contains information about our +dependencies. Since we don’t have any yet, it’s not very interesting. -The `Cargo.lock` file contains information about our dependencies. Since we -don’t have any yet, it’s not very interesting. The `target` directory contains -all the build products, and, as can be seen, Cargo produces debug builds by -default. You can use `cargo build --release` to compile your files with -optimizations turned on: +Once you’re ready for release, you can use `cargo build --release` to compile +your files with optimizations turned on: ```shell $ cargo build --release Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) ``` -`cargo build --release` puts the resulting binary in `target/release` -instead of `target/debug`. +`cargo build --release` puts the resulting binary in `target/release` instead of +`target/debug`. -Compiling in debug mode is the default for development -- compilation time is +Compiling in debug mode is the default for development-- compilation time is shorter since the compiler doesn't do optimizations, but the code will run slower. Release mode takes longer to compile, but the code will run faster. diff --git a/src/doc/book/src/02-05-project-layout.md b/src/doc/book/src/02-05-project-layout.md index 186572251..d66aa7eb1 100644 --- a/src/doc/book/src/02-05-project-layout.md +++ b/src/doc/book/src/02-05-project-layout.md @@ -20,12 +20,14 @@ Cargo project: └── some-integration-tests.rs ``` -* `Cargo.toml` and `Cargo.lock` are stored in the root of your project. +* `Cargo.toml` and `Cargo.lock` are stored in the root of your project (*package + root*). * Source code goes in the `src` directory. * The default library file is `src/lib.rs`. * The default executable file is `src/main.rs`. * Other executables can be placed in `src/bin/*.rs`. -* Integration tests go in the `tests` directory (unit tests go in each file they're testing). +* Integration tests go in the `tests` directory (unit tests go in each file + they're testing). * Examples go in the `examples` directory. * Benchmarks go in the `benches` directory. @@ -37,8 +39,10 @@ description](03-02-manifest.html#the-project-layout). `Cargo.toml` and `Cargo.lock` serve two different purposes. Before we talk about them, here’s a summary: -* `Cargo.toml` is about describing your dependencies in a broad sense, and is written by you. -* `Cargo.lock` contains exact information about your dependencies. It is maintained by Cargo and should not be manually edited. +* `Cargo.toml` is about describing your dependencies in a broad sense, and is + written by you. +* `Cargo.lock` contains exact information about your dependencies. It is + maintained by Cargo and should not be manually edited. If you’re building a library that other projects will depend on, put `Cargo.lock` in your `.gitignore`. If you’re building an executable like a diff --git a/src/doc/book/src/02-06-cargo-toml-vs-cargo-lock.md b/src/doc/book/src/02-06-cargo-toml-vs-cargo-lock.md new file mode 100644 index 000000000..fa0890957 --- /dev/null +++ b/src/doc/book/src/02-06-cargo-toml-vs-cargo-lock.md @@ -0,0 +1,104 @@ +## Cargo.toml vs Cargo.lock + +`Cargo.toml` and `Cargo.lock` serve two different purposes. Before we talk +about them, here’s a summary: + +* `Cargo.toml` is about describing your dependencies in a broad sense, and is + written by you. +* `Cargo.lock` contains exact information about your dependencies. It is + maintained by Cargo and should not be manually edited. + +If you’re building a library that other projects will depend on, put +`Cargo.lock` in your `.gitignore`. If you’re building an executable like a +command-line tool or an application, check `Cargo.lock` into `git`. If you're +curious about why that is, see ["Why do binaries have `Cargo.lock` in version +control, but not libraries?" in the +FAQ](faq.html#why-do-binaries-have-cargolock-in-version-control-but-not-libraries). + +Let’s dig in a little bit more. + +`Cargo.toml` is a **manifest** file in which we can specify a bunch of +different metadata about our project. For example, we can say that we depend +on another project: + +```toml +[package] +name = "hello_world" +version = "0.1.0" +authors = ["Your Name "] + +[dependencies] +rand = { git = "https://github.com/rust-lang-nursery/rand.git" } +``` + +This project has a single dependency, on the `rand` library. We’ve stated in +this case that we’re relying on a particular Git repository that lives on +GitHub. Since we haven’t specified any other information, Cargo assumes that +we intend to use the latest commit on the `master` branch to build our project. + +Sound good? Well, there’s one problem: If you build this project today, and +then you send a copy to me, and I build this project tomorrow, something bad +could happen. There could be more commits to `rand` in the meantime, and my +build would include new commits while yours would not. Therefore, we would +get different builds. This would be bad because we want reproducible builds. + +We could fix this problem by putting a `rev` line in our `Cargo.toml`: + +```toml +[dependencies] +rand = { git = "https://github.com/rust-lang-nursery/rand.git", rev = "9f35b8e" } +``` + +Now our builds will be the same. But there’s a big drawback: now we have to +manually think about SHA-1s every time we want to update our library. This is +both tedious and error prone. + +Enter the `Cargo.lock`. Because of its existence, we don’t need to manually +keep track of the exact revisions: Cargo will do it for us. When we have a +manifest like this: + +```toml +[package] +name = "hello_world" +version = "0.1.0" +authors = ["Your Name "] + +[dependencies] +rand = { git = "https://github.com/rust-lang-nursery/rand.git" } +``` + +Cargo will take the latest commit and write that information out into our +`Cargo.lock` when we build for the first time. That file will look like this: + +```toml +[root] +name = "hello_world" +version = "0.1.0" +dependencies = [ + "rand 0.1.0 (git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9)", +] + +[[package]] +name = "rand" +version = "0.1.0" +source = "git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9" + +``` + +You can see that there’s a lot more information here, including the exact +revision we used to build. Now when you give your project to someone else, +they’ll use the exact same SHA, even though we didn’t specify it in our +`Cargo.toml`. + +When we’re ready to opt in to a new version of the library, Cargo can +re-calculate the dependencies and update things for us: + +```shell +$ cargo update # updates all dependencies +$ cargo update -p rand # updates just “rand” +``` + +This will write out a new `Cargo.lock` with the new version information. Note +that the argument to `cargo update` is actually a +[Package ID Specification](03-07-pkgid-spec.html) and `rand` is just a short +specification. diff --git a/src/doc/book/src/02-06-tests.md b/src/doc/book/src/02-07-tests.md similarity index 94% rename from src/doc/book/src/02-06-tests.md rename to src/doc/book/src/02-07-tests.md index db5ec20af..743a83f85 100644 --- a/src/doc/book/src/02-06-tests.md +++ b/src/doc/book/src/02-07-tests.md @@ -17,7 +17,7 @@ $ cargo test running 0 tests -test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured +test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out ``` If our project had tests, we would see more output with the correct number of diff --git a/src/doc/book/src/02-07-continuous-integration.md b/src/doc/book/src/02-08-continuous-integration.md similarity index 98% rename from src/doc/book/src/02-07-continuous-integration.md rename to src/doc/book/src/02-08-continuous-integration.md index cc10cfe56..f4a4348bb 100644 --- a/src/doc/book/src/02-07-continuous-integration.md +++ b/src/doc/book/src/02-08-continuous-integration.md @@ -4,7 +4,7 @@ To test your project on Travis CI, here is a sample `.travis.yml` file: -``` +```yaml language: rust rust: - stable diff --git a/src/doc/book/src/guide.md b/src/doc/book/src/guide.md index 1bf6af2c4..852d2d81f 100644 --- a/src/doc/book/src/guide.md +++ b/src/doc/book/src/guide.md @@ -8,13 +8,14 @@ about how to use Cargo to develop Rust projects. * [Working on an existing Cargo project](02-03-working-on-an-existing-project.html) * [Dependencies](02-04-dependencies.html) * [Project layout](02-05-project-layout.html) -* [Tests](02-06-tests.html) -* [Continuous Integration](02-07-continuous-integration.html) +* [Cargo.toml vs Cargo.lock](02-06-cargo-toml-vs-cargo-lock.html) +* [Tests](02-07-tests.html) +* [Continuous Integration](02-08-continuous-integration.html) ### Further reading -Now that you have an overview of how to use cargo and have created your first crate, -you may be interested in: +Now that you have an overview of how to use cargo and have created your first +crate, you may be interested in: * [Publishing your crate on crates.io](03-06-crates-io.html) * [Reading about all the possible ways of specifying dependencies](03-01-specifying-dependencies.html) diff --git a/src/doc/guide.md b/src/doc/guide.md index 39b25c2f4..46d4c85f9 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -65,9 +65,10 @@ fn main() { Cargo generated a “hello world” for us. Let’s compile it: -
$ cargo build
-   Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
+```shell +$ cargo build + Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) +``` And then run it: @@ -80,12 +81,12 @@ We can also use `cargo run` to compile and then run it, all in one step (You won't see the `Compiling` line if you have not made any changes since you last compiled): -
$ cargo run
-   Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
-   Running `target/debug/hello_world`
-Hello, world!
+```shell +$ cargo run + Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) + Running `target/debug/hello_world` +Hello, world! +``` You’ll now notice a new file, `Cargo.lock`. It contains information about our dependencies. Since we don’t have any yet, it’s not very interesting. @@ -93,12 +94,13 @@ dependencies. Since we don’t have any yet, it’s not very interesting. Once you’re ready for release, you can use `cargo build --release` to compile your files with optimizations turned on: -
$ cargo build --release
-   Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
+```shell +$ cargo build --release + Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) +``` -`cargo build --release` puts the resulting binary in -`target/release` instead of `target/debug`. +`cargo build --release` puts the resulting binary in `target/release` instead of +`target/debug`. Compiling in debug mode is the default for development-- compilation time is shorter since the compiler doesn't do optimizations, but the code will run @@ -112,15 +114,17 @@ to get going. First, get the project from somewhere. In this example, we’ll use `rand` cloned from its repository on GitHub: -```sh +```shell $ git clone https://github.com/rust-lang-nursery/rand.git $ cd rand ``` To build, use `cargo build`: -
$ cargo build
-   Compiling rand v0.1.0 (file:///path/to/project/rand)
+```shell +$ cargo build + Compiling rand v0.1.0 (file:///path/to/project/rand) +``` This will fetch all of the dependencies and then build them, along with the project. @@ -171,21 +175,23 @@ regex = "0.1.41" Re-run `cargo build`, and Cargo will fetch the new dependencies and all of their dependencies, compile them all, and update the `Cargo.lock`: -
$ cargo build
-    Updating registry `https://github.com/rust-lang/crates.io-index`
- Downloading memchr v0.1.5
- Downloading libc v0.1.10
- Downloading regex-syntax v0.2.1
- Downloading memchr v0.1.5
- Downloading aho-corasick v0.3.0
- Downloading regex v0.1.41
-   Compiling memchr v0.1.5
-   Compiling libc v0.1.10
-   Compiling regex-syntax v0.2.1
-   Compiling memchr v0.1.5
-   Compiling aho-corasick v0.3.0
-   Compiling regex v0.1.41
-   Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
+```shell +$ cargo build + Updating registry `https://github.com/rust-lang/crates.io-index` + Downloading memchr v0.1.5 + Downloading libc v0.1.10 + Downloading regex-syntax v0.2.1 + Downloading memchr v0.1.5 + Downloading aho-corasick v0.3.0 + Downloading regex v0.1.41 + Compiling memchr v0.1.5 + Compiling libc v0.1.10 + Compiling regex-syntax v0.2.1 + Compiling memchr v0.1.5 + Compiling aho-corasick v0.3.0 + Compiling regex v0.1.41 + Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) +``` Our `Cargo.lock` contains the exact information about which revision of all of these dependencies we used. @@ -208,10 +214,11 @@ fn main() { Running it will show: -
$ cargo run
-     Running `target/hello_world`
-Did our date match? true
- +```shell +$ cargo run + Running `target/hello_world` +Did our date match? true +``` # Project layout Cargo uses conventions for file placement to make it easy to dive into a new @@ -345,7 +352,7 @@ re-calculate the dependencies and update things for us: ```shell $ cargo update # updates all dependencies -$ cargo update -p rand # updates just “rand” +$ cargo update -p rand # updates just “rand” ``` This will write out a new `Cargo.lock` with the new version information. Note @@ -364,26 +371,25 @@ the files in `tests`. Here's an example of running `cargo test` in our project, which currently has no tests: -
$ cargo test
-   Compiling rand v0.1.0 (https://github.com/rust-lang-nursery/rand.git#9f35b8e)
-   Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
-     Running target/test/hello_world-9c2b65bbb79eabce
+```shell
+$ cargo test
+   Compiling rand v0.1.0 (https://github.com/rust-lang-nursery/rand.git#9f35b8e)
+   Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
+     Running target/test/hello_world-9c2b65bbb79eabce
 
 running 0 tests
 
 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
-
+``` If our project had tests, we would see more output with the correct number of tests. You can also run a specific test by passing a filter: -
$ cargo test foo
-
+```shell +$ cargo test foo +``` This will run any test with `foo` in its name. @@ -398,7 +404,7 @@ documentation for more details. To test your project on Travis CI, here is a sample `.travis.yml` file: -``` +```yaml language: rust rust: - stable -- 2.30.2